E.PIPHANY Macros 



This appendix describes the built-in macros for SQL and operating-system 
commands thatE.piphany supplies. You can use Epiphany macros in extraction 
jobs, queries against your EpiCenter datamart, and the command line for the 
AppServer. You can also define your own macros with EpiCenter Manager. 
Refer to "Macros," on page 241 for details on creating your own E.piphany 
macros. 



Built-In SQL Macros 

E.piphany provides a number of built-in SQL macros that allow you to write 
extraction jobs and queries against your datamart in a database-independent 
fashion. Where necessary, Rpiphany also provides certain database-specific 
macros. 



SQL Macro Syntax 

The syntax for an Epiphany SQL macro takes the following general form. 
Macro references begin with a pair of dollar signs. Arguments to SQL macros 
are enclosed within square brackets. The separator for arguments is a comma 
surrounded by tilde characters. 
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SQL Macro Syntax 

SS A/IACRO[argument] 
S% MACRO [ argi- , ~ arg2\ 

White space between the macro reference and the opening square bracket of the 
argument list is not allowed. The following example expands correctly: 

$$NVL [ MAX ( COl_l ) - , -0 ] 

The following example does not expand correctly: 

$$NVL [MAX(COl_l)-,-0] 

The Epiphany macro interpreter allows white space between arguments and 
argument separators. However, those white-space characters are passed through 
and appear as part of the expanded SQL statement. Take care to ensure that any 
white-space characters you embed in your arguments list do not adversely 
affect the resulting SQL syntax. 

You can determine the expanded value for most E.piphany macros by issuing 
the following SQL command in an EpiMeta database: 

Select * from translation_actual 

For usage examples, see the initialization file templates.sql in the following 
folder: 

C: \Progrcun Files\Epiphany\ii3stance\Conf igFiles 

Replace C with the drive on which your E.piphany software is installed. 
Replace instance with the name of your E.piphany instance. 
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Database-Independent Macros 

E.piphany supports multiple database servers for EpiCenter datamarts. The 
Epiphany database-independent macros allow you to isolate your datamart 
from syntax differences that result from vendor-specific extensions to SQL. 

Database-independent macros are classified into the following groups: 

• Extraction macros 

• EpiCenter-management macros 

• General-purpose macros 

Each group is discussed in a section that follows. 

Extraction Macros 

The extraction macros listed in Table 19 identify source-system data elements 
such as tables and columns, or destination data elements. The Usage column 
indicates the expected frequency of use for each macro. 

Table 19: Extraction-Set Identification Macros d of 4 

\ Macro Usage Description 



; $$COLUMN_CURRENT_VALUE[ Low ; Expands to the value of the indicated 



table_name 
column_name] 



column as of the start of the current run. 
Can be used to complete a "two-sided" 
WHERE clause that also uses the 
$$COLUMN RANGE FILTER macro. 




table_name - , - column_name 
~,~ alias_name\ 



High 



Expands to a "one-sided" SQL comparison 
expression that requires that 
aliasjiame.columnjiame be greater than 
or equal to the value in table tablejiame 
column columnjiame as of the start of the 
last run. This extracts "everything since 
last time." Although alias_name is 
optional, Rpiphany suggests that you 
include it. 
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Table 19: Extraction-Set Identification Macros 



(2 OF A) 



Macro 



Usage Description 



$$COLU M N_LAST_VALU E[ 
tab/e_name - 
column_name] 



$$COLUM N_RANG E_FI LTER[ 

table_name column^name 
alias_name] 



High 



High 



$$DATE_CURRENT_VALUE 



Low 



$$DATE_FI \J^R[column_name] 



High 



Expands to the value of the indicated 
column as of the start of the last run. This 
expands to a value, not to an expression, 
allowing you to make your own 
expressions. 

Expands to a "two-sided" SQL comparison 

expression that requires 

alias jiamexolumnjxame to be greater 

than or equal to the value in table 

tablejiame 

column column_name as of the start of the 
last run, and less than or equal to this value 
as of the start of the current run. This 
extracts "everything since last time, but not 
including that data that changes while the 
extractions are running." 



Expands to the "current date" as of the start 
of the current run. This expands to a value, 
not to an expression, allowing you to make 
your own expressions. Can be used to 
complete a "two-sided" WHERE clause that 
also uses the 

$$DATE RANGE FILTER macro. 



Expands to a "one-sided" SQL comparison 
expression that requires the column to be 
greater than or equal to the "current 
date/time" as of the start of the last run. 
This extracts "everything since last time." 

No table or alias arguments are available to 
the macro. If the column needs to be 
qualified, just add the qualifications in the 
first argument. For example: 



$$DATE_FILTER[ oo • date_key ] 
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Table 19: Extraction-Set Identification Macros 



(3 OF 4) 



Macro 



Usage Description 

High Expands to the "current date" as of the start 
of the last run. This expands to a value, not 
to an expression, allowing you to make 
your own expressions. 

This compares SQL Server datetimes. The 
column used for the comparison must be 
declared as a datetime or some variant in 
SQL Server. Only the date portion of the 
value is used; the time portion is discarded. 



$$DATE_RANGE_FILTER[ 
column_name] 



I $$YYYYMMDD_CURRENT_VALUE Low 



|$$YYYYMMDD_FILJER[ 
\ column_name] 



High Expands to a "two-sided" SQL comparison 
expression that requires the column to be 
greater than or equal to the "current 
: date/time" as of the start of the last run, and 
less than or equal to the current time as of 
the start of the current run. This extracts 
\ "everything since last time, but not 
including that data that changes while the 
extractions are running." 

This compares SQL Server datetimes. The 
column used for the comparison must be 
declared as a datetime or some variant in 
SQL Server. Only the date portion of the 
value is used; the time portion is discarded. 

Expands to the "current date in 
YYYYMMDD format" as of the start of the 
current run. This expands to a value, not to 
an expression, allowing you to make your 
own expressions. 



High This is the same as a DArE_FILTER except 
that only the "day" portion of the 
date/times is used. (Some business 
semantics are most meaningful when 
applied to "days.") This extracts 
"everything since the last day, including | 
the last day." | 
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Table 19: Extraction-Set Identification Macros 



(A OF A) 



Macro 

$$YYYYMM D p^ij^SlIVA LU E 



High 



$$YYYYMMDD_RANGE_FILTER[ High 
column_name] 



Usage Description 



Expands to the "current date in 
YYYYMMDD format" as of the start of the 
last run. This expands to a value, not to an 
expression, allowing you to make your 
own expressions. 



This is the same as a 

DArE_RANGE_FILTER except that only the 
"day" portion of the date/times is used. 
(Some business semantics are most 
meaningful when applied to "days.") This 
extracts "everything since the last day, 
including the last day, but not including 
today." 



EpiCenter-Management Macros 

The EpiCenter-management macros listed in Table 20 specify data elements 
within your datamart or conditions that might be true with respect to your 
datamart. 



Table 20: EpiCenter Macros 



(1 OF 2) 



Macros 

iicURR 



$$CURREXP 



Usage 

High 

High 



$$CURRHIST 



Description 



Expands to the _A or _B suffix of the currently 
active tables. Allows you to reference the active or 
new EpiMart tables. 



Expands to the _P or _Q suffix of the currently 
active backfeed tables. Allows you to reference 
the active or new EpiMart tables. 



High Expands to the _X or _Y suffix of the currently ■ 
active history tables. Allows you to reference the \ 
active or new EpiMart tables. | 
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Table 20: Epicenter Macros 



(2 OF 2) 



Macros 
$$CURRVIEW 



Usage 

High 



Description 



Expands to the suffix (such as _AX or _BY) of the 
currently active combined view of tables and 
history tables. Allows you to reference the active 
or new EpiMart tables. 



$$DEBUG 



Low 



If debugging in enabled: Expands to nothing if the 
verbosity level of the extract.exe command is less 
than 3; otherwise, returns its argument. Note: For 
testing that depends on whether debugging is on or 
off, use both DEBUG and NOT_DEBUG 



$$INITIAL_LOAD 



i$$MARTDBNAME 



Medium Indicates that timestamps are to be ignored:during 
an extraction job. (The action of this macro is not 
related to the Initial Load semantic type.) 



Medium Returns the name of the datamart database 
(EpiMart). 



$$METADBNAME 



Medium Returns the name of the metadata database 
(EpiMeta). 



$$NEXT 
$$NEXTEXP 



High 
High 



Expands to the _A or _B suffix of the currently 
inactive tables. 



Expands to the _P or _Q suffix of the currently 
inactive backfeed tables. 



$$NEXTHIST 



High 



Expands to the _X or _Y suffix of the currently 
inactive history tables. 



$$NOT_DEBUG 



Lx)w 



If debugging is not enabled: Expands to a null 
value if the extract command's verbosity level is 
higher than 3; otherwise, returns its argument. 
Note: For testing that depends on whether 
debugging is on or off, use both DEBUG and 
NOT DEBUG 



$$NOTJNITIAL_LOAD 



Medium Indicates that timestamps are to be considered 

during an extraction job. (The action of this macro 
is unrelated to the Initial Load semantic type.) 
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General-Purpose Macros 

The macros listed in Table 21 are used for a variety of purposes. 
Table 21: General-Purpose SQL Macros 

Description 



U OF 18) 



Macros 
$$ADD_DAYS 



Usage 



Medium Returns a date representation of its first 
argument plus its second argument as a 
number of days: 

For example: 

SELECT 

$$ADD_DAYS [ $$DBNOW- , -1 ] 



$$AD D_MACRO[ macro- , 
dbtype--,-- value] 



Low Defines a macro or assigns a new value. 

The macro argument is the name of the 
macro. The dbtype argument is the 
database server for which the value 
argument applies. The value argument is 
the value that the macro expands to for 
the indicated database server. 



$$ADD_MONTHS[ 
date_ express/on-- , 
number] 



Medium Takes two arguments; adds the second as 
a number of months to the first argument, 
which is a date. 



$$ ASS E RT_I N D EX_EXI STS[ 
index_name] 



Low Causes an SQL error if the index named 
in argument 1 does not exist. For 
example: 

$$BEGIN_ASSERT_INDEX 
$$ASSERT_INDEX_EXISTS [ 

'XPKCustMap_B] 
$$ASSERT_INDEX_EXISTS [ 

' XPKAppMap_B ' ] 
$$END ASSERT INDEX 
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Table 21: General-Purpose SQL Macros 



(2 OF 18) 



Macros 



$$BATCH_PARALLEL_DEGREE 



Usage Description 

High Sets the parallel degree for extraction 
jobs. The initial value is 4. You can 
change the value with EpiCenter 
Manager. See "Macros," en page 241. 



$$BEGIN_ASSERTJNDEX 



Low In Oracle, declares the DECLARE 

INDEX_NOT_EXISTS exception. See 
$$ASSERT INDEX EXISTS. 



$$BIGDATE 



Lx)w 



i $$BOOl_TO^YH[testva/ue] 



Declares a BIGDATE data type (to 
record millisecond-precision 
timestamps). 



Low Returns the string N if testvalue equals 0. 
Otherwise, returns Y. For example: 

$$B00L_T0_YN[6] 



becomes Y 



$$CASE_BEGIN 



Medium Begins a case statement that compares an 
expression to a list of options and returns 
the value for the first matching option. 
Also provides a single option-value pair. 
For example: 

SELECT 

$$CASE_BEGIN [ col_name- , -opt 

$$CASE_ELSElF[col_naine 

opt2",-val2] 
$$CASE_ELSE [ else_val ] $$CASE 
END 



$$CASE_ELSE 



Medium Fall-through value for a case statement 
that compares an expression to a list of 
options and returns the value for the first 
matching option. See CASE_BEGIN. 
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Table 21: General-Purpose SQL Macros 



(3 OF 18) 



Macros 

iicAsriLsiiF 



$$CASE_END 



Usage Description 

Medium Continues a case statement that compares 
an expression to a list of options and 
returns the value for the first matching 
option. See $$CASE_BEGIN. 

Medium Ends a case statement that compares an 
expression to a list of options and returns 
the value for the first matching option. 
See $$CASE BEGIN. 



$$CAT 



High Used as an operator to append "two" 
$$CAr strings. For example: 

$$T0_CHAR[ table 1 . coll ] 
$$CAT $$CAT 
$$T0_CHAR[COl2] 



$$CBm_yMJitestva/ 
lowerbound ~ 
upperbound ~ 
binletter] 

$$CBIN_END 



Medium Can be used to "bin" numeric values into 
character buckets. Multiple $$CBIN_VAL 
macros should be followed by a single 
$$CBIN_END. If testval is in the range 
lowerbound to upperbound (inclusive), 
then the expression yields binletter. 

For example: 

$$CBIN_VAL[7-,-l-,-5-,~'A' ] 
$$CBIN_VAL[7-,-6-,-10-,-'B' 
] 

$$$CBIN END 



$$CHAR_1 



returns the value B. 



Medium Expands into a type defmition for a 
single character field. 
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Table 21: General-Purpose SQL Macros 



(4 OF 18) 



Macros 

$$counOows^from 
$$count_rows_select 



Usage Description 

Low Can be used to count the number of rows 
in a table. Uses sysindexes on SQL 
Server for fastest count. 
For example: 

SELECT $$COUNT_ROWS_SELECT 
the_count 

$$COUNT_ROWS_FROM[MyTable ] 



$$COU UJERUn/tiaL value] 



Low Returns sequential row numbers for a 
result set, starting with initial _value, if 
supplied. For example: 

SELECT $$COUNTER 
the counter. 



$$CREATEJ N DEXJ F_NOT_EXISTS[ 
index_type-',-' 
index^name--,- 
table^name-,- 
column Jist-','- 
after_ creation^ clause ] 



Low 



Creates an index if it is not already there. 

$$DDL_BEGIN 

$$CREATE_INDEX_IF_NOT_EXIST 
S[ 

UNIQUE -,-XPK_123",- 
tablel-, -ss_key, iss, 
date_key , transtype_key , seq- 

$$DDL END 



$$DBNOW High Returns the date/time from the database. 

For example: 

SELECT 

Coll ss_key 
$ $ DBNOW da t e_modi f led 
from zork 
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Macros 



Usage Description 



$$DDL_BEGIN 



Low Starts a block of code that changes the 
schema. Use outside a DECLARE block. 
For example: 

$$DDL_BEGIN 
$$NOT_DEBUG[ 

$$DROP_TABLE_IF_EXISTS [ 

table] 

] 

$$DDL END 



$$DDL_BEGIN_NO_DECLARE 



Low Starts a block of code that changes the 
schema. Use inside a DECLARE block. 
For example: 

DECLARE $$VAR[txnFIXED] 

$$VARCHAR_50$$EOS 

$ $DDL_BEGIN_NO_DECLARE 

$$ VAR_ASSIGN_BEGIN [ txnFIXED 

] 

SELECT 

$ $TO_CHAR [ trans type_key ] 
$ $VAR_ASS IGN_INTO [ txnFIXED ] 
FROM Transtype_0 WHERE name 
= 'FINV_ADJUST' 
$ $ VAR_ASSIGN_END 



$$DDL_END 



Low Ends a block of SQL that changes the 
schema. For example: 

$$DDL_BEGIN 

$$DROP_TABLE_IF_EXISTS [ 

$$FCTTBL[ ]$$NEXT] 

$ $DROP_TABLE_IF_EXISTS [ 

$$FCTTBL[ ]_INC] 

$$DDL END 
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Table 21: General-Purpose SQL Macros 



(6 OF 18) 



Macros 

$$DDljMCist3temeni] 



Usage Description 

Low All items in the argument list are 
evaluated at runtime, not when the 
statement is parsed. This macro can 
construct SQL based on the values of 
variables computed in the same SQL 
block. For example: 

$$DDL_BEGIN 

$$DDL_EXEC [CREATE INDEX 
X tablel ON tablel 



iss, ss_key, date_key 



( 

) 
] 

$$DDL END 



$$DECLARE_BEGIN 



Low Starts a DECLARE block. For example: 

$ $ DECLARE_BEG IN 

$ $ DECLARE_BOD Y [ $ $ VAR [ 

count_INC] $$EPIINT] 

$ $ DECLARE_BODY [ $ $ VAR [ 

COunt_FC] $$EPIINT] 

BEGIN 

$$VAR_ASSIGN_BEGIN [ cnt_INC ] 
SELECT COUNT(l) 
$$VAR_ASSIGN_INTO [ cnt_INC ] 
FROM $$FCTTBL[ ]_INC 
$$VAR ASSIGN END 



$$DECLARE_BODY[a/-^f//77e/7/'] 



$$DOUBLESTRING 



Low 
Low 



Treats its argument as a declaration. See | 
$$DECLARE BEGIN. 1 



Expands to a VARCHAR data type that 
is used for decimal values in the 
campaign manager. This string type 
eliminates null values, which are not 
allowed in dimension tables. 
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Table 21: General-Purpose SQL Macros 



(7 OF 18) 



Macros 



$$DROPJ N DEXI table_name-, - 
index_name] 



Usage 

Medium 



Description 

Drops the index. For example: 

$$DDL_BEGIN 

$$DROP_lNDEX[tablel-,- 
index_name ] 
$$DDL END 



$$DROP_TABLEJ F_EXiSTS[ 
table_name] 



Medium Drops the table without returning an 
error indicating that the table does not 
exist. For example: 

$$DDL_BEGIN 

$$DROP_TABLE_IF_EXISTS [ tbll 
] 

$$DROP_TABLE_IF_EXISTS [ tbl2 
] 

$$DDL END 



$$ELSE 



Medium The start of the negative clause of an IF 
statement. 



$$END_ASSERTJNDEX 



Low 



$$ENDJF 
$$EOS 



Ends a block of checks that indexes exist. 
See $$ASSERT INDEX. 



Medium Ends an IF statement, see $$IF. 

Low Ends an SQL statement. For example: 

SELECT ' PROCESSED ' , 
COUNT(l), 1100 FROM tablel 
$$EOS 



$$EPIINT 



Medium Declares an integer. For example: 

$ $ DECIiARE_BEGIN 
$$DECLARE_BODY[ $$VAR[ 
unjoined] $$EPIINT] 
$ $ DECLARE_BODY [ $ $ VAR [ 
processed] $$EPIINT] 
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Table 21: General-Purpose SQL Macros 



(8 OF 18) 



Macros 
$$EPIKEY 



Usage Description 



Medium 



$$EXEC_SP[/DAOC~, ^params] 



Lx)w 



i$$FACTMONEY 



; $$FACTQTY 



$$ FLOAT 



\ $$IDENTITY 



%%\^condition] 



Declares an Epiphany dimension key. 
See $$EPIINT. 

Execute a stored procedure. The proc 
argument is the procedure name. The 
params argument is a comma-separated 
list of parameters to the stored procedure. 



Medium 

Medium 
Medium 
Medium 



Declares a monetary value. See 
$$EPIINT. 

Declares a decimal value. See $$EPIINT. 



Declares a float value. See $$EPIINT. 



Declares a integer serial sequence. See 
$$EPIINT. 



Medium Performs a conditional action. For 
example: 

$$IF[$$VAR[fc_exists] = 0] 
$$DDL_EXEC[ 

$$SELECT_INTO_BEGIN [ tmp_tbl 
] 

SELECT 
* 

$ $SELECT_INTO_BODY [ tmp_tbl ] 
FROM 

01d_table 

WHERE 

1=0 

, ] 

$$END_IF 
$$DDL END 



$$\\JRON[[tab/e_namei~. 
table_name2] 



Low 



Performs an inner join on two tables. See | 

$$JOIN WHERE. I 

i 
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Table 21: General-Purpose SQL Macros 



(9 OF 18) 



Macros 



$$INSTR[si~,~5r] 



Usage Description 

Medium Returns the position of in s2. For 
example: 

$$INSTR[ 'b' -,- 'abC ] 



returns 2 . 



$$INTERACTIVE_PARALLEL_DEGREE 



$$JOIN_LEFT_OUTER 



Medium Sets the parallel degree for ad-hoc user 
queries. The initial value is 4. You can 
change the value with EpiCenter 
Manager. 



Medium 



Produces a condition for outer joining the 
first argument to the second. For 
example: 

SELECT 

• • • 

WHERE 

$$JOIN_LEFT_OUTER[tl.Cl 
t2.c2 ] 



$$JOIN_RIGHT_OUTER 



Medium Produces an equals sign appropriate for 
right outer joins (No arguments are 
needed,) For example: 



SELECT 



WHERE 

tl.cl $$JOIN_RIGHT_OUTER 
t2.c2 



398 



Epiphany Confidential 



Built-In SQL Macros 



Table 21: General-Purpose SQL Macros 


(10 OF 18) 




] Macros 


Usage 


Description 




1 $$JOIN_WHEREL/a//L^^V7^/7] 

\ 


Low 


Supplies the WHERE clause for a join. 
For example: 




I 
I 

I 
\ 

\ 




SELECT coll, C0I2 
FROM 

Table 1 s 

$$L0J_FR0M[table2 m-,-s.iss 
= m.iss AND s.col2=m.col2 ] 
$ $L0 J_FROM [ tables 
d~,-m.coll = d.coll] 
WHERE 1=1 

$$ JOIN_WHERE [ m. coll=d . col 1 ( 
+ )] 

$$JOIN_WHERE[s.iss = m.iss 
(+) AND S.C0I2 = m.col2 
( + )] 




\ 
\ 
\ 

\ 
i 

i 

\ 






|$$LENGTH[s] 

I 

\ 
\ 

! 


Medium 


Returns the length of a string. For 
example: 

$$LENGTH[ 'abC ] 

returns 3 . 


1 

1: 


^Utini FROMl /nin rnnHitinn^ 


Low 


Performs a left outer join. See 
$$JOIN_WHERE, 


% 


f $$LONGSTRINR 

\ 

\ 

J 

\ 

\ 
! 


Low 


Expands to a VARCHAR data type that is 
used for decimal values in the campaign 
manager. This string type eliminates null 
values, which are not allowed in 
dimension tables. 


i 

* 


1 $$/VlAX_SYS_DAfE 

j 


Medium 


Returns the highest date supported by the 
database. 


i 


|$$METADBNA^AE 

\ 
1 


Medium 


Returns the name of the current metadata . 
database (SQL Server) or schema 
(Oracle). 


»■ 
1 
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Table 21: General-Purpose SQL Macros 

Macros Usage 
$$M0 DU LO[Ar ~, ~y] Low 



$$MONEYSTRING Low 



$$N BIN.VAU testvai-, - 
lowerbound - 
upperbound ~ 
binnumber] 

\ $$NBIN_END 



; $$NO_FROM_LIST Medium 



(11 OF 18) 

Description 

Returns the remainder when x is divided 
byy. 

For example: 

MODULO{7-,-4] 

returns 3. 

Expands to a VARCHAR data type that is 
used for decimal values in the campaign 
manager. This string type eliminates null 
values, which are not allowed in 
dimension tables. 



$$NBIN_VAL[7-,-l-,-5~,-l] 
$$NBIN_VAL[7-,-6-,-10-,- 2] 
$$NBIN_END 

return the value 2. 

Supplies the "dummy" FROM clause 
needed by some database vendors. For 
example: 



Medium Can be used to "bin" numeric values into 
numeric buckets. Multiple $$NBIN_VAL 
macros should be followed by a single 
$$NBIN_END. If testval is in the range 
lowerbound to upperbound (inclusive), 
then the expression yields binnumber. 
For example: 



SELECT ' MODIFIED ' , 
$ $VAR[ modified ] , 1050 
$ $N0_FROM_LI ST$ $EOS 

\ 
; 

SSNUMBERfe.s) Medium Declares a decimal(9,5). See $$EPIINT. 
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(12 OF 18) 



Macros 

$$NVL[ex/7A£»55/a/7% -value] 



Usage 

High 



$$0 RACLE[ expression] 



High 



Description 

When the first argument is NULL, replace 
it with the value in the second argument. 
For example: 

SELECT 

$ $TO_CHAR [ $ $NVL [ MAX ( col 1 ) - , 
"1]] 



Expands to nothing if the database is not 
Oracle. For example: 

SELECT COUNT(l) 
FROM 

$$SQLSERVER[ sysobjects ] $$0R 
ACLE[tabs] 



$$ RAI S E.EXCEPTI 0 N[ exception] 



Low 



$$REMOVE_MACRO[/77^rA^7] 



Low 



$$RENAME_OBJECT 



Raises the given exception (as a variable 
on Oracle, as a string on SQL Server). 
For example: 

$$RAISE_EXCEPTION[MyExcepti 
on] 

raises an exception. 

Removes the definition of the macro 
indicated by the macro argument. 



Medium Renamed tables or other database 
objects. For example: 

$ $RENAME_OB JECT [ oldtablenam 
e - , -nevrtblname ] 
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(13 OF 18) 



Macros 

$$ii[icriNTO3EGIN[ 
table_name] 



Usage 

High 



Description 



Creates a table from a SELECT statement. 
Expands into a CREATE TABLE AS or a 
SELECT INTO statement. For example: 

$$SELECT_INTO_BEGIN [ temp_ta 

SELECT 
* 

$$SELECT_INTO_BODY [ temp_tab 
] 

FROM 
01d_tab 
WHERE 
1=0 



$$SELECT_INTO_BODY[ 
table_name\ 



High 



(See "Oracle Macros," on page 407 for 
more additional similar macros.) 



, $$SMALLDATE 



$$SMALLINT 



Medium 



Medium 



$$SQLSERVER[eA^Ae55/£7/7] 



High 



$$SSKEY 



Low 



Creates a table from a SELECT statement. 
Expands into a CREATE TABLE AS or a 
SELECT INTO statement. See 
$$SELECT INTO BEGIN. 



Declares a SMALLDATETIME. See 
SSEPHNT. 



Declares a double-byte integer. See 
$$EPIINT. 

Expands into nothing if the database 
engine is not SQL Server. For example: 

SELECT COUNT{l) 
FROM 

$$SQLSERVER[sysobjectS]$$OR 
ACLE[tabs] 



Declares the type Epiphany uses for 
ss_keys. See $$EPIINT. 
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Table 21: General-Purpose SQL Macros 



(lA OF 18) 



' Macros 


Usage 


Description 


: $$SUBSTRING[eA'/7/e55/o/7~,~ 


Medium 


Performs a substring operation. For 


1 start--, "length] 




example: 






$ $ SUBSTRING [ name- , - 1 - , - 8 ] 



$$SUPERNVL 



Medium Converts a null value for the first 

argument into the second argument. The 
resulting column is not nullable in the 
schema definition of the result set. 

For example: 

SELECT 

$$SUPERNVL[COll-,- 'UNKNOWN' ] 



$$TAB LE_EXI STS.CO N D I Tl 0 N[ 
table^name] 



Low 



Detects if a table exists. For example: 

SELECT COUNT(l) 
FROM 

$$SQLSERVER[sysobjects]$$OR 

ACLE[tabs] 

WHERE 

$$TABLE_EXISTS_CONDITION [ ta 
ble_name ] 



$$TABLE_WITH.PREFIX[ Medium 
database^name-,-' table_name] 



$$TINYINT 



Medium 



M 



Qualifies a table name with a database or 
user name. 
For example: 

SELECT 

source_system_key iss 
FROM 

$$TABLE_WITH_PREFIX[ 
$$METADBNAME","' 
source_systein ] 

Declares a single-byte integer. See 
$$EPIINT. 
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Table 21: General-Purpose SQL Macros us of is) 

Macros Usage Description 

%ii^6JiH^ High Converts a value to a character string. In 

Oracle, the value must be numeric. For 
example: 

\ SELECT 

$$T0_CHAR[$$NVL[MAX(COll) ] ] 



As an alternative, you can use the 
$$TO_CHAR_UNIVERSAL macro, which 
accepts both numeric and nonnumeric 
values. 

$$T0_CHAR_UNIVERSAUf»xpr£»55/a/7] Medium Converts a value to a character string. 

Converts a value to a database date with 
the following format: 

MM/DD/YYYY HH24:MM:SS 



$$TOJ)AJE[express/on] Medium 



I $$TO_DATEFMTl expr-, -format] Low 



$$TO_EPI DATE[ expression] High 



MM is the month in two-digit notation, 
DD is the two-digit day, yYJTis the year, 
HH24 is the hour in 24-hour notation, 
MM is the two-digit minute, and SS is the 
two-digit second. 

Converts expression to a date type with 
the appropriate Oracle format (format is 
ignored on SQL Server). 



Converts a date to the string format 
preferred by EpiChannel. This macro 
should be used for all columns that have 
physical type SMALLDATE. For 
example: 

Select coll ss_key, 

$$TO_EPIDATE [ date_col ] 
date_modif led 
from 2ork 
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Table 21: General-Purpose SQL Macros 

Usage 



(16 OF 18) 



Macros 
$$TO_HHMMS^ 



$$TOJ HJ[express/on] 



$$TO_N U M B E R[ express/on] 



Description 



Medium Converts a datetime variable to a string 
of the form: hhwmss where hh represents 
the hour, WM represents the minute, and 
ss represents the second. 



Medium Converts expression to an integer type. 



Medium Converts an expression to a number. 
For example: 

$$T0 NUMBER[ ' 123' ] 



returns 123. 



$$TO_TI M E[ expression] 



Medium 



Converts its argument to a time 

representation. 

For example: 

SELECT $$TO_TIME[$$DBNOW] 



\ $$10_YT/\tAN[DD[express/on] 

\ $$lR^HS[AJE_y^[{express/on-,- 

searchval-, ~ 
I translationval-, - 
\ nestedcalh, ~ 

$$TRANS LATE_ELS EI of/^d-zrer/T?]] 

\ $$TRANSLATE_ELSE 
• $$TRANSLATE_END 



Medium 
Medium 



Converts a data to a YYYYMMDD string. 



Searches expression for occurrences of 
each searchval and returns the 
translationval. Note that 
$$TRANSLArE_VAL terms should be 
nested inside of each other. An optional 
$$TRANSLArE_ELSE can be nested 
inside the final $$TRANSLATE_VAL. For 
example: 

$ $TRANSLATE_BEGIN 
$$TRANSrjATE_VAL [ ' abcdef ' - , - 
bce-,-'Valuel 
$$TRANSLATE_VAL [ ' abcdef 
ode-,- 'Value2'-,- 
$$TRANSLATE_ELSE [ ' Other * ] ] ] 
$ $TRANSLATE_END 

returns Value2. 



Epiphany Confidential 



405 



Appendix A: Epiphany Macros 



Table 21: General-Purpose SQL Macros 



Macros 

$$TRANSTYPE[/7J/77e] 



$$UNKNOWN_DATE 



$$VAR[ variable^name] 



$$VAR_ASSIGN_BEGIN[ 
variable^name] 



High 



Medium 



(17 OF 18) 



Usage Description 



Returns the transtype number 
corresponding to the name that is the first 
argument of the macro. 



Expands to a date of the form 
MM/DD/mr (01/01/1990 by 
default). You can set a new value in this 
same format with EpiCenter Manager. 
See "Macros," on page 241. 



Medium References a database variable. For 
example: 

SELECT ' PROCESSED ' , 
$$VAR[processed] , 1100 
$$N0 FROM LIST$$EOS 



Medium Assigns to a database variable. For 
example: 

$$VAR_ASSIGN_BEGIN [ max_key ] 
SELECT $$T0_CHAR[$$NVL[ 
MAX(COll)-',-l] ] 
$$VAR_ASSIGN_INTO[max_key] 
FROM table2 
$$VAR ASSIGN_END 



$$VAR_ASSIGN_END 



$$VAR_ASSIGNJNTO[ 
variable^name] 



$$VARCHAR_5 



$$VARCHAR_15 



Medium 



Medium 



Medium 



Medium 



Assigns to a database variable. See 
$$VAR ASSIGN BEGIN. 



Assigns to a database variable. See 
$$VAR ASSIGN BEGIN. 



Declares a variable-width character 
datatype that holds a maximum of 5 
characters. See $$EPIINT. 

Declares a variable-width character 
datatype that holds a maximum of 15 
characters. See $$EPIINT. 



406 



E.piphany Confidential 



Built-In SQL Macros 



Table 21: General-Purpose SQL Macros 



(18 OF 18) 



Macros 

$$VARCHAR_25 
$$VARCHAR_50 



$$VARCHAR_ioo 



$$VARCHAR_255 



Usage 

Medium 



Medium 



Description 

Declares a variable-width character 
datatype that holds a maximum of 25 
characters. See $$EPIINT. 

Declares a variable-width character 
datatype that holds a maximum of 50 
characters. See $$EPIINT. 



Medium Declares a variable-width character 

datatype that holds a maximum of 100 
characters. See $$EPIINT. 



Medium Declares a variable-width character 
datatype that holds a maximum of 
255characters. See $$EPIINT. 



Database-Specific SQL Macros 

This section lists macros and discusses concerns that apply to specific database 
servers. 



Oracle Macros 

Oracle-specific SQL macros control the physical characteristics of an Oracle 
Epicenter. Oracle tables are stored in a logical entity called a tablespace. 
Because of the various size requirements of EpiCenter objects, such as fact 
tables and indexes, dimension tables and indexes, EpiCenter allows you to 
configure which tablespace is used for each object type. When appropriate, the 
expansions of Oracle-specific SQL macros refer to tablespace names. 
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Table 22: Oracle-Specific SQL Macros 



Macro 



Description 



$$ANALYZE_TABLE[fa^)/e_name] 



$$DIMINDEX_TABLESPACE 



$$DIMTABLESPACE 



$$FACTINDEX_TABLESPACE 



$$FACnABLESPACE 



$$METATABLESPACE 

$$SELECTJNTO_BEGIN_OPTl 
table^name, option^string] 

$$S E LECT_I NTO_B EG I N_TS[ 
table_name, tablespace] 



$$TEMP_TABLESPACE 



Performs a size-based analysis of the 
indicated table. 

Used for dimension indexes (including those 
on aggregates and mini-dimensions). 

Used for dimension tables (including 
aggregates and mini-dimensions). 

Used for fact indexes (including those on 
aggregates and clusters). 

Used for fact tables (including aggregates and 
clusters, as well as temporary objects used 
during semantics). 

Expands to the name of the tablespace to use 
for metadata tables on your system. 

Expands to a CREATE TABLE statement. The 
optionjstring argument passes a list of 
options to the resulting statement. 

Expands to a CREATE TABLE statement. The 
tablespace argument passes the name of the 
desired tablespace for the new table to the 
resulting statement. 

Used for all Application Server temporary 
tables (those needed for query post- 
processing at runtime). 



Normally, the values for these macros are set to match the names of the 
tablespaces as they are created by the Oracle initialization script provided by 
E.piphany as described in the E.piphany e.4 Installation Guide. 
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To use alternate names for these tablespaces, you need to run SQL statements 
such as the following against your EpiMeta database. 

update translation_Actual set actual_string = 

' your_tablespace_name' where store_type = 'Oracle' and 

translation_string = ' FACTTABLESPACE ' 



SQL Server Data Types and Epiphany Macros 

Fact semantic types that use aggregation operators, such as SUMQ, are sensitive 
to decimal data types such as number ( x,y ) . When new tables are created with 
SELECT INTO Statements based on aggregates of these data types, columns that 
use those data types expand to hold the largest decimal value. This expansion 
can unnecessarily increase the overall size of the fact table. For this reason, both 
FACTQTY and FACTMONEY map to the MONEY data type in SQL Server. 
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SQLServer Macros 

The following macros apply to SQL Server, 

Table 23: SQL Server Macros 



Macro 



Usage Description 



$$TIMESTAMP_FILTER[ 
column_name] 



High 



$$TI M ESTAM P.LAST.VA LU E 



High 



$$TI M ESTAM P_RANG E.FI LTE R[ High 
column^name] 



Expands to a "one-sided" SQL comparison 
expression that requires the column to be 
greater than or equal to the current 
timestamp as of the start of the last run. This 
extracts "everything since last time." 

This compares timestamps, which actually 
have no time or date information in them. 
The column used for the comparison must be 
declared as a timestamp type, not as a time or 
date. 



Expands to the "current timestamp" as of the 
start of the last run. This expands to a value, 
not to an expression, allowing you to make 
your own expressions. 



Expands to a "two-sided" SQL comparison 
expression that requires the column to be 
greater than or equal to the current 
timestamp as of the start of the last run, and 
less than or equal to the current time as of the 
start of the current run. This extracts 
"everything since last time, but not including 
that data that changes while the extractions 
are running." 

This compares timestamps, which actually 
have no time or date information in them. 
The column used for the comparison must be 
declared as a timestamp type, not as a time or 
date. 
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System-Call Macros 

Epiphany system-call macros allow you to encapsulate operating-system 
commands in extraction jobs. You typically use system-call macros to pass 
filenames or user names that have been stored in metadata to operating-system 
commands. Many commands, such as RENAME and DIR, are unable to read a 
database, and few commands can read E.piphany-created structures. 

System-Call Macro Syntax 



\ %$AMCRO[argument] 

I 

{ $%A/IACRC{argj, arg2\ 

Names specific data stores can be abstracted within the job definition through 
the use of data-store roles. See "System Calls," on page 79 for more 
information about roles. Unless stated otherwise, the arguments for a macro are 
the names of data-store roles that have been defined for an extraction job. 

You can use multiple arguments in most cases, which results in an expansion of 
each argument. Note that the expansion of both of the following macros is the 
same: 

$$macro[argl, arg2] 
$$macro[argl] $$macro[arg2 ] 

If a macro reference does not match the name of a macro that has been defined, 
the extraction job halts with an error. If the argument to a macro is a role name, 
and the job does not define that role, the extraction job halts with an error. 

Table 24, on page 412 lists the E.piphany system-call macros. 
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Table 24: Lpiphany System-Call Macros d of a) 



Macros 


Purpose 


Usage 


Description 


$$AGG 


Child 
Procs 


High 


The name of the AggBuilder executable 
in $$EProiN. For example: 

$$AGG $$EXC_ARGS -j 
$$JOB_NAME 


$$APPSERVERHOST 


Registry 


Low 


The value of this Registry variable. 


$$APPSERVERPORT 


Registry 


Low 


The value of this Registry variable. 


$$CHARTSLOGFILE 


Registry 


Low 


The value of this Registry variable. 


$$CHARTSOUTPUTDIR 


Registry 


Low 


The value of this Registry variable. 


$$DATABASE[A0/e] 


Database 
Login 


High 


Translates to the name of the database or 
instance when the data-store role is 



associated with a specific database server 
(that is, not a data store of type ODBC or 
File). For example: 



isql /S $$SERVER[MyRole] /U 
$$USER[MyRole] /P 
$$PASSWORD(MyRole] /d 
$$DATABASE[MyRole] /w 300 
/i /Q "gen_tests_run" 



$$DBVEND0R[A£7/e] 
$$DEBUG_LEVEL 



Database Medium Translates to the vendor of the database 
Login server associated with a data-store role. 

Command Low Translates to the current verbosity level 
Line of EpiChannel. Use this to pass 

EpiChannel's verbosity onto the 
subprocesses it spawns via system calls. 
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Table 24: Lpiphany System-Call Macros 



(2 OF 41 



Macros 

$$blRNAME[r(7A?] 



Purpose 

File ID 



Usage Description 

Medium Translates to the directory name of the 
data store associated with role, without 
the last filename component and without 
a trailing slash. If the role is WorkingDir, 
the directory name's last component is a 
unique subdirectory generated for this 
particular run of EpiChannel. For 
example: 

echo "DIRNAME is " 
$$DIRNAME [WorkingDir] 



$$DSN 



$$EPIBIN 
$$EXC 

$$EXC_ARGS 
$$EXC_CMD 



Database Medium Translates to the ODBC connection string 
Login for the database. This string may be 

generated even for databases accessed 

using native APIs, 

Child Medium The name of the Wm32 directory under 

Procs the InstanceRootDir Registry variable. 

Child High The name of the extract.exe executable 

Procs in $$EPIBIN. 

Child High The recognized portions of the 

Procs extract.exe command line. 

Child Medium The extractexe program and its 

Procs arguments other than job name. You can 

use this to fire subsidiary runs. For 

example: 

$$EXC_CMD -j performance 
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Table 24: Lpiphany System-Call Macros 

Macros Purpose Usage 

$$FI LENAME[ A^7/^] File ID Medium 



$$INSTANCE_NAME 
$$INSTANCEROOTDIR 
$$JOB_NAME 
i $$RASSW0RD[A7/e] 

; %%PI^H[role] 

$$PROGRAM_NAME 

$$REG1STRY_EPIPATH 

SSSERVERIro/e] 

$$SQLNETlAO/e] 



Registry Medium 

Child Low 
Procs 

Child High 
Procs 

Database High 
Login 

File ID Medium 

Child Low 
Procs 

Registry Low 

Database High 
Login 



(3 OF A) 

Description 

Translates to the filename of the data 
store associated with role. If the role is 
WorkingDin the file name is the name of 
the EpiChannel log file. For example: 

echo "FILENAME is " 
$$FILENAME [Working Dir] 

The name of the instance's Registry 
subtree. 

Value of the InstanceRootDir Registry 
variable. 

The name of the current job. 

The password for the user of the 
database-server or host associated with 
the indicated data-store role. 

Translates to the full pathname of the file 
that is associated with role. 

The name of the current extractexe 
program. 

Name of the E.piphany Registry key. 

Translates to the name of the database 
server for the data store that is associated 
with role. For SQL Server, this is the 
hostname of the computer on which the 
database server resides. For Oracle, this is 
the SQLNet ID (SID). SERVER and 
SQLNET are identical in behavior and can 
be interchanged. The data-store type must 
be a specific database server (not ODBC 
or File.) 
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Table 24: Epiphany System-Call Macros 



(A OF 4) 



\ Macros 
;$$USER 



SSVERSIONiA^j/f*] 



Purpose Usage Description 



Database 
Login 



High 



Database Low 
Login 



The user name for the database-server or 
host associated with the indicated data- 
store role. 

Translates to the version number (or 
string) of the database server that is 
associated with role. The data-store type 
must be a specific database server (not 
ODBC or File). 
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